                                Texture Mapping

INTRODUCTION

 	This doc is written for people who want to cut the bullshit and
 	program texture mapping.
 	Two months ago I got my first inet account (yeah yeah, your probably
	laughing now) and it was great. When I first joined the #coders
 	channel it seemed like heaven :-), I listened and I talked and I
 	had lots of fun, but one thing was missing...
 	I did not know anything about 3d coding, or f/x coding for that
	matter. The lack of knowledge I had was caused by my experience
	in system programming, so when you look at my sources you will
	probably understand why they are not so optimized and why they are
	written quite differently from other people's sources.
	The lack of knowledge made me feel bad, so I began to learn about
	gfx and started looking at demos.
	My main problem was the extreme lack of any good documents and sources
	on the subject.
	Some of the documents I read were written in a goal to explain
	the mathematical aspect of the effects, I, however, was not too
	interested in the mathematical background, just the interesting
	stuff. So I looked further and found other documents. This time they
	were for real beginners, and so I had to read some boring texts
	on how to write a pixel, which is not one of life's greatest
	pleasures. Then there were the med-docs, the ones aimed at people
	like me with some background but with no experience in 3d stuff.
	Those docs missed the target completely! They are usually written
	by someone who didn't have any power to write them, or had no idea
	what he was talking about. Those docs usually meant getting loads
	of formulas and uncommented sources, which simply did not help
	at all.

	I would like to change that in this doc by giving a good explanation
	on how to do texture mapping, and by giving two sources, one in
	pascal and one in c++. All of this so that as many people as
	possible, will be able to learn how to do texture mapping and will
	have some sort of a chance making their own mappers without getting
	a huge headache, or nagging IRC dudez with questions they do not
	want to answer because it is too long for IRC :)

	Ok, enough blabbering, lets get to work...



TERMS

	U,V - U is the texture X, V is the texture Y. I will use U1,U2,V1,V2.

	INTERPOLTAION - Interpolation means for us, stepping between
	two values using a constant step value. What for? speed.
        Example:
                               len=10 (count if you don't believe!)
		        U1=0 ---------- U2=255

	Lets say we want to find for each point on the above line, it's U
	value. The way to do that would be to calculate the ratio
	between the line's length and the "length" between U1 and U2.

	              U2-U1   255-0
	DeltaU = dU = ----- = ----- = 25.5
		       len     10

	So if we were to find the U value at the 2nd point of the line
	we would do:

		U=X*dU=2*25.5=51

	All of this is very useful since we can now step through the
	first point of the line to the last point and find out the U
	value for each and every point.
	All we do is set our U to U1, and calculate our dU.
	The pesudo code will look like this:

		U = U1;
		X = X1;

		dU = (U2-U1)/(X2-X1);

		loop from X1 to X2
			X=X+1;
			U=U+dU;
		end loop

	This way you can see that we only add to get U and we do not use
	a MUL like in the first equation.
	Interpolation ,by the way, is probably the most important way
	to gain speed at costful calculations involving MULs and DIVs.


        FIXED MATH - Many docs have a section on this, so I will give
        one too. (This explanation deals with the fixed math that
        relates to texture mapping, and not in general)

        When doing texture mapping a great deal of DIVs is involved. The
        problem with DIVs is that they are both slow and require a special
        type of variable to deal with, i.e float,real.
        Using these types is not efficient for real time effects, so
        a trick is made to avoid using them.
        The only different between a real/float variable and an integer
        one is the fraction part of the variable. What you want to do is
        represent a fraction using an integer, but how?

        Lets say you have to divide 3 by 2, the result will be 1.5, but
        saving 1.5 inside an integer will cut off the fraction and leave
        the 1.
        But what would happend if you took the same numbers and muled one
        of them by 256?
        The result will be:

          (3*256)/2 = 384

        As you can see the result is storeable inside an integer.
        But what really happened?
        Take a look at the integer itself:

        At the beggining we had the number 3 in the low part of the
        integer

                     low         |    high
             bit 0 1 2 3 4 5 6 7 | 8 9 0 1 2 3 4 5
                 1 1 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0
                      3          |

        Then we muled it by 256, and now it is in the high part

                     low         |    high
             bit 0 1 2 3 4 5 6 7 | 8 9 0 1 2 3 4 5
                 0 0 0 0 0 0 0 0 | 1 1 0 0 0 0 0 0
                                 |     3

        Then we took the number, which is 768 (3*256) and dived it by
        2. what we got was this

                     low         |    high
             bit 0 1 2 3 4 5 6 7 | 8 9 0 1 2 3 4 5
                 0 0 0 0 0 0 0 1 | 1 0 0 0 0 0 0 0
                      128        |     1


        Since all the bits in the high part have values which are exactly
        256 times larger than their pairs in the low part, we can say that
        the high part has a value of 256 and the low part has a value of
        128, adding them together yields 384.
        Looking at it with a bit of imagination, you can see that the high
        part holds the integer, and the low part holds the fraction.
        Taking the value 384 and diving it by 256 will yeild 1.5! which
        is our real number. Also our fraction is 0.5, and how much is
        0.5 of 256? 128.

        But storing isn't everything, you need to do ADDs and SUBs on it,
        and here is where the trick is.
        If you need to interpolate between 0 and 255 in 3 steps, you can
        do the following:

        Using real numbers:

            Step value = 255/3 = 85

            Step 1 -- 0+85   = 85
            Step 2 -- 85+85  = 170
            Step 3 -- 170+85 = 255

        Using fixed math:

            Step value = (255*256)/3 = 21760

            Step 1 -- 0+21760     = 21760
            Step 2 -- 21760+21760 = 43520
            Step 3 -- 43520+21760 = 65280 (255*256=65280)

        Now you ask yourself, so what did I get from this? well take a good
        look and see that if you divide each of your fixed math values
        with 256 you will get: 85, 170, 256.
        Those are the same values as in the real number calculations.
        But I made extra MUL and 3 extra DIVs using fixed math!
        So where is the speed you ask?
        Ahh here steps in the wonderfull SHIFTS. Shifting by 8 gives the
        same result as muling/diving by 256!
        This makes fixed math a very fast way to use fractions without using
        the FPU or real numbers.

        Take the same steps and use shifts:
        (SHL = <<, SHR = >>)

            Step value = (255 SHL 8) / 3 = 21760

            Step 1 -- 0+21760     = 21760 -> 21760 SHR 8 = 85
            Step 2 -- 21760+21760 = 43520 -> 43520 SHR 8 = 170
            Step 3 -- 43520+21760 = 65280 -> 65280 SHR 8 = 255

        A small note is that if you shift by 16 you will get a much more
        precise fraction and by doing so you can get better results.

	SCAN-CONVERT - This means to step along the edges of a line in
	order to find it's values on a certain axis. Usually this axis
	is the X axis.
	The keyword is again -- interpoltaing.
	The explanation is in the main part.

MAIN PART

	Let us first discuss the concept of scanconverting the polygon.

   SCAN-CONVERT

	There are many ways to scan convert. Each has it's advantages and
	it's disadvantages, but basically all use interpolation in their
	code.
	When I scanconvert for a texture mapper, or basically for
	any polygon routine, I use triangles.
	The reason for this is that I have a fixed-small amount of
	sides (3 of them.)
	[I have been told that there is some sort of a mathematical trick
	involving triangles, that allows you to get rid of some DIVs.
	But due to problems with my inet, I can not talk to anyone so that
	I might know the trick.]

	The most common methods are either using a buffer into which
	you feel in values, Or making the scan built into your texture
	mapper. The second way is more fast, since less time is used
	for accessing the memory. The first way has one advantage that
	comes to mind now, which is it's capability to scan any given
	number of sides with the same routine and with great ease.
	I chose to use the "built-in" way, so that is what I will explain
	to you next.

	First we will take a look at a triangle:

	            (5,5)
	              1
	             /\
	            /  \
	           /    \
	          /      \
	         /        \
        (1,10)2 /__________\ 3(10,10)

	(The fact that both sides are equal in length has no relevance to us)

	This triangle is a special case, y2=y3. I did it so that the first
	explanation will be as simple as possible.

	Since I usually do not work in ModeX, it is easier for me to scan
	along lines and find each point's X coordinate, so that I could
	use these coordinates to make horizontal lines.
	(If I used ModeX, I would gain more speed by using vertical lines
	 since I will only have to set the bit plane once for a whole
	 line)

	At the begging, you need to sort your points and find the top most
	point in your polygon. This is done so that you could advance
	in the Y axis in a simple way.
	Now what you need to do is interpolate. And in order to do that
	you need to make some DIVs.
	The interpolation of the screen coordinates is easy. Since you
	want to make horizontal lines, you step through each Y and find
	the left X coordinate and the right X coordinate.
	To find the step of each line you do this:

		(X2-X1)/(Y2-Y1) = dX

	or in our case, going along line 1-2:

		(1-5)/(10-5) = -4/5

	This means that for each increase in Y , you add to the X value
	-4/5. Do the same with line 1-3, and you can scanconvert.

	NOTE: Always add to the Y2-Y1, 1. The reason is simple, if you
	      were to do the step on Y3-Y2 you would get a result of 0, which
	      will lead to a divide by zero. So by adding 1 to your length
	      you can avoid that. If your length becomes -1, in situations
	      that I can not think of right now, it is wise to do an OR LEN,1
	      instead of ADD LEN,1. Doing this ensures that your length
	      will never be 0, while as adding 1 to -1 will result in 0 again.

	Here is a pesudo code:

	sort points
	leftx  = x1;
	rightx = x1;
	y = y1;

	dX1 = (X2-X1)/(Y2-Y1);
	dX2 = (X3-X1)/(Y3-Y1);

	loop from Y1 to Y2
		leftx  = leftx+dX1;
		rightx = rightx+dX2;
		y = y+1;
	end loop

	Remember this code is used only when your polygon has y2=y3.
	Now lets discuss polygons when y2 is not equal to y3.


	        (5,5)
	          1
	         /\
	        /  \
               /   / 2(8,7)
	      /  /
	     / /
            //
           /
           3
	 (1,11)

	As in the previous case we sort to find the top most Y.
	When looking at this polygon you can see that it could be cut into
	2 parts. from y=5 to y=7(line 1-2), and from y=7 to y=11(line 2-3).
	This means that you can split the processing of the polygon into
	2 separate parts so that you could have an easier time coding it.
	At the begging of your code do the same as the last time. Calculate
	the dX for line 1-2 and for line 1-3 and initialize your data.
	The only difference here is that you need to stop in the middle
	of the polygon and "switch" lines.
	What do I mean "switch" lines? simple. If you notice, you will see
	that line 1-3 extends through the whole polygon, so there is no
	real need to stop because of it. But line 1-2 does stop and there
	is a need to make some more calculations for line 2-3.
	What this all means is that you need to calculate for line 1-3
	the dX at the beginning and simply continue adding on it with
	no change. However, on line 1-2 you must stop and reassign your
	data.
	So pesudo code looks like this:


	sort points
	leftx  = x1;
	rightx = x1;
	y = y1;

	dX1 = (X2-X1)/(Y2-Y1);
	dX2 = (X3-X1)/(Y3-Y1);

	loop from Y1 to Y2
		leftx  = leftx+dX1;
		rightx = rightx+dX2;
		y = y+1;
	end loop

	dX1 = (X3-X2)/(Y3-Y1); **switched lines from 1-2 to 2-3

	loop from Y2 to Y3
		leftx  = leftx+dX1;
		rightx = rightx+dX2;
		y = y+1;
	end loop

	As you can see here, the only difference is an extra loop for the
	last line. Note that the line from 1-3 does not need to be
	recalculated or touched at all.

	Thats it, you can scan convert.


   TEXTURING

	The actual texturing is just another interpolation.
	This time you interpolate the texture coordinates instead of the
	screen coordinates.
	First a reminder, U1 is the texture X1, U2 is X2, V1 is the texture
	Y1 and V2 is Y2.
	So lets have a look at another weird ascii picture and see what
	we need to do:

				(0,0)		(255,0)
				 1		   2
				  -------------
				 |            /
				 |          /
				 |        /
				 |      /
				 |    /
				 |  /
				 |/
				 3
				(0,255)

	As you can see here each point in the polygon has two values,
	U and V. Our goal is to interpolate those values along each
	line and then plot the horizontal lines.
	What we do is interpolate between values like this, line 1-2:

		dU = (U2-U1)/(Y2-Y1)
		dV = (V2-V1)/(Y2-Y1)

	Now try to look at the polygon and to understand why I divided
	by the Y. The idea is simple, in each line you will make a certain
	number of steps, in which you will have to fully interpolate
	the texture coordinates. Our number of steps depends on the number
	of Ys we will pass. For example, if we were to pass 2 ys from
	point 1 to point 2, then the U value will have to start at 0, which
	is it's value at point 1, and end at 255, which is it's value at
	point 2. So in order for it to do that in 2 steps it must increase
	by 127.5 each step.
	And the formula will look like this:

		dU = (U2-U1)/(Y2-Y1) = (255-0)/(2-0) = 255/2 = 127.5

	You do the same thing for the V value:

		dV = (V2-V1)/(Y2-Y1) = (0-0)/(2-0) = 0/2 = 0

	The complete step calculations will be:

	Line 1-2 -- dU = (U2-U1)/(Y2-Y1) = (255-0)/(0-0) = ?
	                 (look at the note in the scan-convert section for
	                  an explanation on how to avoid dividing by 0)
	            dV = (V2-V1)/(Y2-Y1) = (0-0)/(0-0) = ?

	Line 1-3 -- dU = (U3-U1)/(Y3-Y1).
	            dV = (V3-V1)/(Y3-Y1).

	Line 2-3 -- dU = (U3-U2)/(Y3-Y2).
	            dV = (V3-V2)/(Y3-Y2).

	Ok and now to the pesudo code again:

	sort points **sort screen points
	leftx = x1; **initialize the screen coordinates
	rightx = x1;

	leftu = u1; **initialize the texture coordinates
	rightu = u1;
	leftv = v1;
	rightv = v1;

	y = y1;
	dX1 = (X2-X1)/(Y2-Y1); **find the screen deltas
	dX2 = (X3-X1)/(Y3-Y1);

	dU1 = (U2-U1)/(Y2-Y1); **find the texture deltas
	dU2 = (U3-U1)/(Y3-Y1);
	dV1 = (V2-V1)/(Y2-Y1);
	dV2 = (V3-V1)/(Y3-Y1);

	loop from Y1 to Y2
		leftx  = leftx+dX1;
		rightx = rightx+dX2;

		leftu  = leftu+dU2;
		rightu = rightu+dU1;
		leftv  = leftv+dV2;
		rightv = rightv+dV1;

		y = y+1;
	end loop

	dX1 = (X3-X2)/(Y3-Y1); **switched lines from 1-2 to 2-3
	dU1 = (U3-U2)/(Y3-Y2);
	dV1 = (V3-V1)/(Y3-Y2);

	loop from Y2 to Y3
		leftx  = leftx+dX1;
		rightx = rightx+dX2;

		leftu  = leftu+dU2;
		rightu = rightu+dU1;
		leftv  = leftv+dV2;
		rightv = rightv+dV1;

		y = y+1;
	end loop

	After you finished this you can go on to the last part of texture
	mapping, interpolating for the last time!

	Take a look at what you got after doing all of the above:

	(0,0)
	 1                              (0,0)                     (255,0)
	 |\			         -------------------------------
	 | \                            |                       --------|
         |  \                           |               --------        |
	 |   \                          |       --------                |
  (0,127)|____\2(255,0)          (0,127)|-------                        |
	 |    /                         |                               |
	 |   /                          |                               |
	 |  /                           |                               |
	 | /                             -------------------------------
         |/                             (0,255)                 (255,255)
	 3
	(0,255)

        As you can see from this diagram, the horizontal line creates
        a sloped line in the texture. So what can we do about that?
        Interpolate.
        Which means making a new set of values and interpolating them.
        Lets define new values, I,J which are our coordinates in the texture.
        Therefor, stepping on the texture line will call upon the next
        equations:

                  dI = (rightu-leftu)/(rightx-leftx)
                  dJ = (rightv-leftv)/(rightx-leftx)

        From these equations you can now interpolate along the line in the
        texture and get the color of each and every point on that line.
        So what is left? Basicly nothing, what you do now is move from
        the left x to the right x, and plot the pixels.
        Getting the pixel color will be done by your I,J values which
        are interpolated as you go on the horizontal line.

        Last and final pesudo code:

	sort points **sort screen points
	leftx = x1; **initialize the screen coordinates
	rightx = x1;

	leftu = u1; **initialize the texture coordinates
	rightu = u1;
	leftv = v1;
	rightv = v1;

	y = y1;
	dX1 = (X2-X1)/(Y2-Y1); **find the screen deltas
	dX2 = (X3-X1)/(Y3-Y1);

	dU1 = (U2-U1)/(Y2-Y1); **find the texture deltas
	dU2 = (U3-U1)/(Y3-Y1);
	dV1 = (V2-V1)/(Y2-Y1);
	dV2 = (V3-V1)/(Y3-Y1);

	loop from Y1 to Y2

                x  = leftx; **initialize the plotting variables
                i  = leftu;
                j  = leftv;

                dI = (rightu-leftu)/(rightx-leftx); **find the texture deltas
                dJ = (rightv-leftv)/(rightx-leftx);

                loop from leftx to rightx
                     plot(x,y,texture[I,J]); **put the pixel on the screen
                     i = i+dI;
                     j = j+dJ;
                     x = x+1;
                end loop

		leftx  = leftx+dX1;
		rightx = rightx+dX2;

		leftu  = leftu+dU2;
		rightu = rightu+dU1;
		leftv  = leftv+dV2;
		rightv = rightv+dV1;

		y = y+1;
	end loop

	dX1 = (X3-X2)/(Y3-Y1); **switched lines from 1-2 to 2-3
	dU1 = (U3-U2)/(Y3-Y2);
	dV1 = (V3-V1)/(Y3-Y2);

	loop from Y2 to Y3

                x  = leftx; **initialize the plotting variables
                i  = leftu;
                j  = leftv;

                dI = (rightu-leftu)/(rightx-leftx); **find the texture deltas
                dJ = (rightv-leftv)/(rightx-leftx);

                loop from leftx to rightx
                     plot(x,y,texture[I,J]); **put the pixel on the screen
                     i = i+dI;
                     j = j+dJ;
                     x = x+1;
                end loop

		leftx  = leftx+dX1;
		rightx = rightx+dX2;

		leftu  = leftu+dU2;
		rightu = rightu+dU1;
		leftv  = leftv+dV2;
		rightv = rightv+dV1;

		y = y+1;
	end loop


   OPTIMIZING

        Well optimizing the pesudo codes I gave is probably endless.
        There are so many things to do, but I will mention only those
        that pop up off the top of my head.

        First make all your divs using fixed math (see TERMS).
        Here is an example:

           You want to find dX1, when X1=0, X2=50 and the LEN=15.

           dX1 = (X2-X1)/LEN = (50-0)/15=3.33

           using fixed math this would look like this

           dX1 = ((X2-X1) SHL 8)/LEN = ((50-0) SHL 8)/15 = 12800/15 = 853.

        If you do not understand how this works, try it with other numbers
        and rethink the concept of fixed math. If you do not succeed
        then go to other docs, there are hundreds of docs and examples
        for this subject, so that is why I did not expand on the it.
        (And it's 2:00am! so I don't really care if you don't understand)

        Another thing to do is get rid of some DIVs. You can do that by
        making a small look-up table. Basicly you would think that the
        look-up table would be huge, but it won't.
        When making texture maps, it is recomended that you use fixed
        sized textures, and make a different procedure for each.
        In my case textures are in the size of 256, which is easy to
        manipulate yet has a high definition.
        Because of this fact I know that my U2-U1, U3-U1, etc will either
        be 0/len, or 255/len. (This is true only if you alwyas texture
        map from the edges of your texture, which I do)
        0/len will always equal 0, therefor I do not have to do the DIV
        and I can simply set the variable to 0. In the case of 255/len
        I know from what value to what value len ranges. It is the width
        of my resolution, or in mode 13h, 320. If this is the case then
        making a table with 320 entries that holds all possible combinations
        of 255/len, will be both easy and very low on memory.

        After you have done this you have already saved quite a few DIVs.
        Other than that, try to make the best sorting algorithm you can
        think of. And if you are really into it, try to find a way and
        get rid of the 2 divs per line.


   CLOSING WORDS

        I hope this document has helped you. I know it would have helped me
        had I goten it when I was starting.
        If not then keep looking for docs, or try looking for me :)
        In the next document I will explain phong basing on some explanations
        from here, so if I get bored I will add it to this document and then
        you should be able by now to exit your editor and read the phong
        document.

        Ways to contact me?
        Well try looking for me on the IRC, I go by the name of Dr.
        (Sorry no EMAIL)

                                        Bye bye
                                               Dr

   GREETS GO TO

        Epsilon
        Gnome
        Civax
        Stain
        Kamikaz
        GooRoo
        Lumpy
        NiX
        Quantum
        pGeist
        ae
        winghead
        And the rest of the IRC dudes I have ever talked to.